# Appendix C: Authentication Data Storage

After Helix Universal Server has authenticated user access, it can check whether the user has permission to view specific clips or directories. You can use this information for applications such as pay-per-view. Permission information is stored in a separate database, and this appendix describes the data storage methods that you can use with the authentication feature.

# Understanding Authentication Data

To authenticate visitors, the Helix Universal Server stores user IDs and passwords or client IDs, and their associated access permission information. When a client tries to access a clip, the Helix Universal Server looks up this information to see whether the client or visitor is authorized to view the clip. The information can be stored in either a series of text files or in a database. Templates for common databases are installed during installation.

This section describes the methods for storing user name and password data. Templates for common databases are created during installation, that correspond to the database types listed in "Supported Database Types".

- Text file storage—this default method uses a combination of directory structure and text files to achieve a sensible data storage method. See "Using Text Files" for details.

- Database templates—the supplied templates use a structure similar to the text file method, in a more familiar database format. Refer to "Using a Database" for more information.

# Using Text Files

The default configuration uses the text file storage method to provide storage for all default realms. The following directories contain the text files which store data. The center letter indicates the authentication protocol: `r` is for `RealSystem 5.0`, `b` is for `Basic`.

Supplied Data Storage Directories
Directory Name | Information Stored
--- | ---
`enc_b_db` | encoder user authentication for Helix Producer
`enc_r_db` | encoder user authentication for RealProducer G2 through 8.5
`adm_b_db` | Helix Administrator user authentication
`con_r_db` | content authentication

The following table describes the contents of these directories.

Text File Storage Directory Structure
Directory | Contents | File or Directory Description
--- | --- | ---
Main directory (`con_r_db`, `enc_b_db`, `enc_r_db`, or `adm_b_db`) | `ppvbasic.txt` | The text file indicates to Helix Universal Server that this is the storage area for the list of authenticated names.
`users` | (initially blank) | Files in this directory list the clips and permission types.
`guids` | (initially blank) | For player validation, files connect the clientID with a user name.
`logs` | `reglog.txt accesslog.txt` | See below for a description of these files.
`redirect` | (initially blank) | For player validation, files contain an URL to which to send the client if redirection is necessary.

The actual data storage text files do not exist when Helix Universal Server is first installed. They are created when authentication is in use, and secure content is first requested. When Helix Universal Server creates the file structure, it creates the `ppvbasic.txt` file. Helix Universal Server looks for this file the second and subsequent times you start it. If the file does not exist, it recreates the directory structure.

| Warning! Do not delete the `ppvbasic.txt` file! If you delete the `ppvbasic.txt` file, Helix Universal Server will rewrite the directories and erase their prior content.

## Users Directory

The files in this directory are named `username`, where `username` is the user name. This directory contains one file per registered user. The first line of each file has the following format and is different than subsequent lines in the file:

    password;uuid;uuid_writeable

Field | Description
--- | ---
`password` | When user authentication is in use, this stores the password. Otherwise shows an asterisk (*). Passwords are encrypted. See "Using the Password Tool".
`uuid` | In player validation, stores playerID. In user authentication, an asterisk (*) appears in this field.
`uuid_writeable` | A flag set and used by Helix Universal Server: `0`–playerID is in database `1`–record created, but playerID is not yet registered

The second and subsequent lines of each file have the following format. For further detail on allowable values in each field, see table "Permission Types":

    url;url_type;permission_type;expires;debitted_time

Field | Description
--- | ---
`url` | URL of secure directory or clip.
`url_type` | Whether URL is directory or clip: `0`–clip `1`–directory
`permission_type` | Permission type associated with access.
`expires` | If `permission_type` is `1`, this is the expiration date/time, in format `MM/DD/YYYY:HH:MM:SS`. Otherwise blank.
`debitted_time` | If `permission_type` is `2`, this is time remaining in seconds. If `permission_type` is `3`, this is the number of seconds of material the visitor has viewed. Otherwise, it is blank.

The example file, `user1,` has the following content, when player validation is in use:

    *;00001d00-0901-11d1-8b06-00a024406d59;0
    Secure/clip1.rm;0;0;*;*
    Secure/directory;1;0;*;*
    Secure/time.rm;0;2;*;300;*
    Secure/time.rm;0;1;05/24/1970:06:12:32;300;*

| Note: If you manually edit the files, be sure that any blank or unused fields use an asterisk (`*`) as a placeholder. Do not use a space for a placeholder.

## Guids Directory

The files in this directory are given the names of the unique client IDs from the registered clients, one per registered user. Each file contains only the name of the associated user name. For example, a file such as `00001d00-0901-11d1- 8b06-00a024406d59` contains the name of the user, `user1`.

## Logs Directory

This directory contains two files: `reglog.txt` and `accesslog.txt`.

### reglog.txt

Each line of `reglog.txt` represents the result of an attempt to register a visitor. This file has the following format:

    status;userid;uuid;IP;register_time;url_redirect

Field | Description
--- | ---

`status`

Result of user's attempt to connect:
`0`–Success
`1`–Failed (clientID not readable)
`2`–Failed (clientID already used)
`3`–Failed (RealAudio Player 3 or older)
`4`–No user (Must be entered previously in the database)
`5`–General failure

`userid` | Unique name of up to 50 characters.
`uuid` | clientID.
`IP` | IP address from which user is attempting to connect.
`request_time` | Time of connection request.
`url_redirect` | If connection failed, URL to which user was redirected (see `redirect.txt`).

### accesslog.txt

Each line of `accesslog.txt` describes the result of an attempt to view a clip. This file is not created until authentication is enabled and the first user attempts to connect:

    status;userid;uuid;ip;url;access_type;permission_on;start_time;end_time;total_time;
    why_disconnect

Field | Description
--- | ---
`status` | Result of user's attempt to connect: `0`–access to clip granted `1`–denied
`userid` | Unique name of up to 50 characters.
`uuid` | Stores player ID.
`ip` | IP address from which user is attempting to connect.
`url` | Secured clip user is attempted to access.
`access_type` | Permission type associated with access. See the table "Permission Types" for values.
`permission_on` | Permission type associated with URL: `0`–file (individual clip) `1`–directory `2`–none
`start_time` | Time/date clip started playing.
`end_time` | Time/date clip stopped playing.
`total_time` | Total time clip played.
`why_disconnect` | Reason for disconnection: `0`–client disconnected voluntarily `1`–server access expired

## Redirect Directory

Used only in player validation, the `redirect` directory contains files named after URLs that are restricted from unauthorized users. Within each file is the alternate URL to which Helix Universal Server sends the user if he or she tries to click the restricted URL. If no files are present in this directory, and the user attempts to click a URL to which he or she has not been given access, the user receives an error message.

Because certain characters that appear in URLs are illegal in file names, Helix Universal Server requires a substitution for these illegal symbols.

Substitutions
Character | Replacement Sequence
--- | ---
`/` | `+2f`
`\` | `+2b`
`+` | `+5c`

For example, the URL `Secure/TopSecret.rm` would be converted to `Secure+2fTopSecret.rm`. The URL within each file, however, is represented normally.

# Using a Database

This section describes the structure of the database templates included with Helix Universal Server. To set up the database, see "Setting Up Other Types of Data Storage". The database templates include five tables:

- Users table—Together with the permissions table, contains the lists of who is registered and with what access.

- Permissions table—Linked to the users table, lists specific clips and directories and the permissions associated.

- Register_log table—Used if player validation is in use, it tracks the clientID.

- Redirect table—Used in player validation only.

- Access_log table—Used by the commerce feature.

## Users Table

Gives the list of user names and passwords.

Users Table
Field | Description
--- | ---
`userid` | User name of up to 50 characters. Ties to permissions table.
`password` | In user authentication, this stores the password. Otherwise blank. Passwords are encrypted.
`uuid` | In player validation, stores clientID. In user authentication, an asterisk (*) appears in this field.
`uuid_writeable` | A flag set and used by Helix Universal Server: `0`–clientID is in the database `1`–the record has been created but the clientID is not yet registered with Helix Universal Server.

## Permissions Table

Linked to the users table through the userid, this identifies the specific clips or directories and the type of access for each.

Permissions Table
Field | Description
--- | ---
`userid` | User name of up to 50 characters. Ties to Users table.
`url` | URL of secure directory or clip.
`url_type` | Whether URL is directory or clip: `0` clip `1` directory.
`permission_type` | Permission type associated with access.
`expires` | Permission expiration date and time, in format `MM/DD/YYYY:HH:MM:SS`. Used only if `permission_type` is `1` (dated). Otherwise blank.
`debitted_time` | If `permission_type` = 2 (countdown), this is the number of seconds remaining. If `permission_type`=3 (countup), this is the number of seconds of material the visitor has viewed. Otherwise, it is blank.

## Register_Log Table

The register_log table is used only if player validation is in use (indicated by `UseGUIDValidation=True`)`.`

Register_log Table
Field | Description
--- | ---

`status`

Result of user's attempt to connect:
`0`–Success
`1`–Failed (clientID not readable)
`2`–Failed (clientID already used)
`3`–Failed (RealAudio Player 3 or older)
`4`–No user (Must be entered previously in the database)
`5`–General failure

`userid` | Unique name of up to 50 characters.
`uuid` | Stores clientID.
`ip` | IP address from which user is attempting to connect.
`request_time` | Time of connection request.
`url_redirect` | If connection failed, URL to which user was redirected (see Redirect Table, above).

## Redirect Table

The redirect table is only used in player validation.

Redirect Table
Field | Description
--- | ---
`url` | URL of any secure clip or directory.
`url_redirect` | URL to which users could be redirected to if they are not allowed access to that clip. New URL must not be a secure URL.

## Access_log Table

Used by the commerce feature to show which secure content has been accessed.

Access_log Table
Field | Description
--- | ---
`status` | Result of user's attempt to connect: `0`–access to clip granted `1`–denied
`userid` | Unique name of up to 50 characters.
`uuid` | Stores player ID.
`ip` | IP address from which user is attempting to connect.
`url` | Secured clip user is attempted to access.
`permission_type` | Permission type associated with access. See the table "Permission Types" for values.
`permission_on` | Permission type associated with url: `0`–file (individual clip) `1`–directory `2`–none
`start_time` | Time/date clip started playing.
`end_time` | Time/date clip stopped playing.
`total_time` | Total time clip played.
`why_disconnect` | Reason for disconnection: `0`–client disconnected voluntarily `1`–server access expired

# Setting Up Other Types of Data Storage

Support for two types of databases is included.

| To set up your Windows computer for ODBC compliance:

1. On the Start menu, point to Settings, and click Control Panel.

2. Double-click 32bit ODBC.

3. On the System DSN tab, click Add.

4. Select your ODBC driver from the list of drivers and click Finish.

5. In the ODBC SQL Server Setup dialog box, type the data source name. Click Select.

6. Type or browse for the path to your database file and click OK.

7. Click OK to exit the ODBC Data Source Administrator.

You must now tell Helix Universal Server where to find your database.

| To set up the supplied database application on UNIX:

1. At a command line, start the database by typing the following:

    ./msql2d &

2. Create the database by typing the following:

    ./msqladmin create databasename

3. Note that whatever you type for `databasename` will need to match the database cited in the Databases list.

4. Create the tables using the database text file by typing the following:

    .msql -h localhost databasename < ppvdemo.db

Be sure to include the less-than sign (<).

| © 2002 RealNetworks, Inc. All rights reserved. For more information, visit RealNetworks Click here if the Table of Contents frame is not visible at the left side of your screen.